#include-once
; feel free to tap into this in your apps, I do.

#cs
  corz gui window animation effects v0.2.1
  functions to simplify window open/close animations

  (c) cor + corz.org 2006->tomorrow!


	function list..
	[see the functions themselves for more detailed usage instructions]

		corz_GUIAnimateOpen( [window handle[, string/array{animation codes}[, string{ini file path}[, string{ini section}]]]])

		corz_GUIAnimateClose( [window handle[, string/array{animation codes}[, string{ini file path}[, string{ini section}]]]])

		corz_GUIFadeIn( window handle )

		corz_GUIFadeOut( window handle )

		corz_GUIGetFX( [string{fx setting} [, string{path to ini file} [, string{ini section} [, string{ini key}]]]])

			[private] corz_ValidateFXCodes( string/array{animation codes}[, string{ini file path}[, string{ini section}]]])


	In most cases, you will only need to interact with the two main functions:
	corz_GUIAnimateOpen() and corz_GUIAnimateClose(). They will access the other
	functions in the background, saving and restoring settings to and from your
	specified ini file, performing the desired window animations, and so on.

	You can also interact directly and easily with corz_GUIFadeIn() and
	corz_GUIFadeOut(), and even corz_GUIGetFX(), if you feel the need.



; The functions..
;

  corz_GUIAnimateOpen()
  Animate the opening of a window.

	Feed it the window handle and (optionally) some animation codes (which can
	be a simple string, like "slide right" - which means it slide out of the
	right hand side). Optionally feed it the path to your ini file, and the
	section of that ini to use for (re)storing settings..

		corz_GUIAnimateOpen( [window handle[, string/array{animation string/codes}[, string{path to ini} [, string{section name}]]]])

	Simplest usage..

		corz_GUIAnimateOpen($my_gui)

	Which is the same as..

		corz_GUIAnimateOpen($my_gui, "Slide Right")

	"Slide Right" being the default gui animation (remember, it was designed for
	wee tools, that most often, at least on my system, find themselves in the
	far-right corners).

		corz_GUIAnimateOpen($my_gui, "Slide Top Right")

	Is also nice.

	Available animation strings..
	[strings are case-insensitive; supplied strings & their case are retained in your ini]

		To fade in/out							use:	"fade" ; note, this doesn't use a dll call.
		To Slide in & out from the left			use:	"slide left", "left", "Slide L", or "L"
		To Slide in & out from the right		use:	"slide right", "right", "Slide R", "Slide", or "R"	(default fx)
		To Slide in & out from the top			use:	"slide top", "Slide T", "Top", or "T"
		To Slide in & out from the bottom		use:	"slide bottom", "Slide B", "Bottom",  or "B"

		To Slide in & out from the top-left		use:	"Slide Top Left", "Top Left", "top-left", "tl", "diagonal tl", "d"
		To Slide in & out from the top-right	use:	"Slide Top Right", "Top Right", "top-right", "tr", "diagonal tr"
		To Slide in & out from the bottom-right	use:	"Slide Bottom Right", "Bottom Right", "bottom-right", "br", "diagonal br"
		To Slide in & out from the bottom-left	use:	"Slide Bottom Left", "Bottom Left", "bottom-left", "bl", "diagonal bl"

		To Explode/implode						use	:	"explode/implode", "Explode", "Implode", or "X"

		To Disable Window Animation FX			use:	"Disable window animation", "Disabled", or "-"

	If you want your user's animation settings to be stored and retrieved
	between launches, but don't want to write the code for that, simply supply
	the optional 3rd and 4th parameters; the full path to an ini file, and the
	name of the section within that file..

		corz_GUIAnimateOpen($my_gui, "bottom", "test.ini", "my fx")

	Which will open the window, sliding it up from the bottom, and save this
	preference to "test.ini", in the section [fx]. It's no problem to use
	your main ini section, in that case a key named "gui_fx" will be written
	with the current animation string.

	If you want to save some animation setting, but not actually animate the
	window (for instance, when a user selects a preference from a menu), simply
	send an empty string for the window handle, and specify some valid ini
	parameters..

		corz_GUIAnimateOpen("", "bottom", "test.ini", "my fx")

	It's slightly non-standard, I know, but it saves you ever having to interact
	with corz_GUIGetFX() directly, which I thought you might like.

	Used in this manner, corz_GUIAnimateOpen() will return valid animation
	codes, which you may or may not wish to use later. See corz_GUIGetFX()
	for a larger explanation of how these codes might be used. One reason why
	you might use these codes is that they are slightly faster to operate.

	GUI fx doesn't create any global variables*, so it's a good idea to make
	$my_codes (or whatever you call it) global in your application, available
	for whenever you need to animate a window.

	You will probably want to do that when you first initialize your
	window..

		global $my_codes = corz_GUIAnimateOpen($my_gui, "", $ini_path, $ini_section)

	If the animation string is left blank "", settings will be retrieved from
	the ini file, if one is specified (and created if not). In either case,
	corz_GUIAnimateOpen() will return the valid animation codes for later use.
	If the ini's gui_fx string is invalid or simply doesn't exist, or you
	didn't specify valid ini paramters, the default setting will be applied.

	As well as returning the valid animation codes array, corz_GUIAnimateOpen()
	sets an environment variable (the name of the current "gui_fx" setting) to
	the simple string version of the animation setting, as saved in the ini
	file. You can use this to set menu selections, checkbox items, or whatever.

		GUICtrlSetData($combo, EnvGet('gui_fx'))

	Although it's usually 'gui_fx', you may have multiple window animations
	running concurrently, so it could be something else. See corz_GUIGetFX() for
	details on how to override this value. Note: these environment variable are
	destroyed when you quit the application.

	Whatever happens, if you specify valid ini parameters, corz_GUIAnimateOpen()
	will attempt to save the current setting to the specified ini at the end of
	its operation.


	Usage examples..

		Retrieve saved setting from the ini, and animate the window using those
		setting. This is most useful when the application first launches..

			corz_GUIAnimateOpen($my_gui, "", "test.ini", "my fx")


		Save the setting "Slide Top" to the ini file, perform no animation. This is
		most useful when the user selects a preference from a menu or some other
		selector..

			corz_GUIAnimateOpen("", "Slide Top", "test.ini", "my fx")

		"Slide Top" could come from anywhere..

			corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $my_app)


		Open the window, animating it up from the bottom, and save that setting
		to the ini file. Perhaps the user okayed a preference dialog, and now
		the main gui is re-opening with updated setting..

			corz_GUIAnimateOpen($my_gui, "bottom", "test.ini", "my fx")


	Examples of how to automate implementation of GUI fx in your code..

		The long-winded versions of the animation strings are most useful; they
		can be used directly in menus, which greatly simplifies the code
		required to implement user-selectable window animations.

		It's fairly easy to animate directly from either saved ini settings, or
		user-selected preferences, or just save and retrieve settings, or both,
		and keep both those things synchronized in the process.

		Giving the user control is always a good thing (particularly when it's
		in layers of expertise), and personally, I like my tools to attach to
		specific areas of my desktop. The bonus of having these tools "slide
		out" of a particular area of the desktop only adds to the user's feeling
		of control.

		So let's say we wanted to create a tray menu for the user to select an
		animation style for your (their) program. The trick is, when we create
		the menu items, we use the actual text of the animation strings.

		Here's a complete tray menu you can rip right off the page..

			TrayCreateItem("")
			global $TrayMenuWinAnim = TrayCreateMenu("Window animation..")

			; we could re-use this array to create other controls (see the included example scripts)..
			local $win_anims[11] = ["Slide Left", "Slide Right", "Slide Top", "Slide Bottom", _
									"Slide Top Left", "Slide Top Right", "Slide Bottom Right", "Slide Bottom Left", _
									"Explode/Implode", "Fade", "Disable window animation"]

			global $menu_items_win_anim[11]
			for $i = 0 to 10
				$menu_items_win_anim[$i] = TrayCreateItem($win_anims[$i], $TrayMenuWinAnim, -1, 1)
				TrayItemSetOnEvent(-1, "MenuSetWinAnim")
			next

			for $i in $menu_items_win_anim
				if TrayItemGetText($i) = $my_fx then TrayItemSetState($i, $TRAY_CHECKED)
			next
			TrayCreateItem("")

		We can then use this exact same text to set the animation fx in the
		called function. Our fictional MenuSetWinAnim() function would be a
		skinny thing that might look very much like this..

			func MenuSetWinAnim()
				corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), "test.ini", "my fx")
			endfunc

		Or, if you wanted to grab the animation codes array for later use (a
		good idea, and while we're with the good ideas, you would of course be
		using variables of some sort)..

			func MenuSetWinAnim()
				global $my_codes = corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $section)
			endfunc

		Then, whenever you need to animate any window, you simply feed the codes
		to the animate functions, like so..

			corz_GUIAnimateOpen($my_gui, $my_codes)

		Even if you didn't get the codes, or even know the animation string, you
		could still perform the window's current animation, like so..

			corz_GUIAnimateOpen($my_gui, EnvGet('gui_fx'))


		All parameters are optional. You can retrieve settings, or save settings,
		or perform a window animation, or any or all of those things at once.

		Simply put; If you want an animation, include the gui handle. If you
		don't want an animation, don't. If you want to save or retrieve
		settings, include ini parameters. If you want to save settings, include
		the animation string, and if you want to retrieve settings, don't.

		See the included "corz_gui_fx [tray+combo example].au3" and "corz_gui_fx
		[combo example].au3" for simple working demos of gui fx.

#ce
func corz_GUIAnimateOpen($some_gui="", $GUIFX="", $ini_file="", $ini_section="")

	if not $some_gui then
		return corz_GUIGetFX($GUIFX, $ini_file , $ini_section)
	else
		if not IsArray($GUIFX) then
			$GUIFX = corz_ValidateFXCodes($GUIFX, $ini_file, $ini_section)
		endif

		switch $GUIFX[1]
			case "-" ; animation has been disabled
				GUISetState(@SW_SHOW, $some_gui)
				return
			case "fade" ; we won't use the dll call version of the fade, it's nasty.
				corz_GUIFadeIn($some_gui)
			case else
				DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $some_gui, "int", 200, "long", $GUIFX[1])
				Sleep(50)
				GUISetState(@SW_SHOW, $some_gui)
		endswitch
		return $GUIFX
	endif
endfunc

; corz_GUIAnimateClose()
; Animate the closing of a window.
;
; Usage as corz_GUIAnimateOpen() (above)
;
; Note: At the end of this function, the window is in a HIDDEN state.
;
func corz_GUIAnimateClose($some_gui="", $GUIFX="", $ini_file="", $ini_section="")

	; I'd love to slip this in somehow, to release the memory (at least, in appearance)
	; but there's just no way to do it without flashing the window, afaik.
	; GUISetState(@SW_MINIMIZE, $some_gui) ; I tried *everything* :/

	if not $some_gui then
		return corz_GUIGetFX($GUIFX, $ini_file, $ini_section)
	else
		if not IsArray($GUIFX) then
			$GUIFX = corz_ValidateFXCodes($GUIFX, $ini_file, $ini_section)
		endif
		switch $GUIFX[1]
			case "-"
				GUISetState(@SW_HIDE, $some_gui)
				return
			case "fade"
				GUISetState(@SW_SHOW, $some_gui)
				corz_GUIFadeOut($some_gui)
			case else
				GUISetState(@SW_SHOW, $some_gui)
				DllCall("user32.dll", "int", "AnimateWindow", "hwnd", $some_gui, "int", 200, "long", $GUIFX[2])
;				Sleep(50)
				GUISetState(@SW_HIDE, $some_gui)
		endswitch
		return $GUIFX
	endif
endfunc


; fade-in..
;
; you can access these two directly, too.
func corz_GUIFadeIn($some_gui)
	WinSetTrans($some_gui, "", 0)
	GUISetState(@SW_SHOW, $some_gui)
	for $i = 0 to 240 step 15
		WinSetTrans($some_gui, "", $i)
		Sleep(5)
	next
	WinSetTrans($some_gui, "", 255)
endfunc

; and out
; sadly, setting the transparency away from max causes the window to flicker briefly.
; but that's still better than the dll call version, which can basically disable the
; parent gui permanently.
func corz_GUIFadeOut($some_gui)
	for $i = 240 to 15 step - 15
		Sleep(5)
		WinSetTrans($some_gui, "", $i)
	next
	GUISetState(@SW_HIDE, $some_gui)
endfunc


; This enables you to send everything directly to corz_GUIAnimateOpen/Close()
;
;
; if we are already working with the animation codes, go away quickly, get on
; with the animaton. if we need to create valid codes, or it's a simple disable
; or fade, invoke corz_GUIGetFX().

func corz_ValidateFXCodes(ByRef $GUIFX, $ini_file="", $ini_section="")
	if IsArray($GUIFX) then return
	$GUIFX = corz_GUIGetFX($GUIFX, $ini_file, $ini_section)
	return $GUIFX
endfunc


#cs
	corz_GUIGetFX( [string{fx setting} [, string{path to ini file} [, string{ini section} [, string{ini key}]]]])

	All parameters are optional.

	This function validates the supplied animation string (retrieving it from
	the ini if no code/string is supplied), and returns an array of valid
	animation codes for later use, possibly by corz_GUIAnimateOpen/Close()

	If the supplied string is invalid, corz_GUIGetFX() makes it valid. Finally,
	if valid ini parameters were specified, the new animation string is saved to
	the ini file..


	Feed it the path and section name of the ini file you would like to use to
	(re)store the settings, and your chosen setting (or omit that, if you want
	corz_GUIGetFX() to grab it from the ini file, or create it anew, if no
	ini setting exists). See corz_GUIAnimateOpen(above) for a list of the
	available animation strings.

	As with corz_GUIAnimateOpen(), the long-winded versions can be used directly
	in menus..

			$menu_item[2] = TrayCreateItem("Slide Right", $TrayMenuWinAnim, -1, 1)
			TrayItemSetOnEvent(-1, "MenuSetWinAnim")

	Inside our fictional MenuSetWinAnim() function we would need to do no more
	than..

		$my_codes = corz_GUIGetFX(TrayItemGetText(@TRAY_ID), $ini_path, $section)

	This does ezactly the same thing, but *slightly* slower..

		$my_codes = corz_GUIAnimateOpen("", TrayItemGetText(@TRAY_ID), $ini_path, $section)

	Either way, if the user selects the item with the text "Slide right" (or
	whatever), corz_GUIGetFX() returns the valid animation codes into
	$my_codes (now an array) for later use. Then, when you need to animate any
	window, you simply feed this to the animate functions, like so..

		corz_GUIAnimateOpen($my_gui, $my_codes)

	and corz_GUIAnimateOpen() will choose the correct code ($my_codes[1]) and
	perform the required animation. $my_codes can hang around your application
	for whenever you need to animate a window (i.e. make it global).

	Of course, you can also call the open and close functions to perform these
	operations, but I figured you may want to access them directly, too.

	Whichever way you go, to you, the coder, and to the user, it's just a bunch
	of cute strings.

	Usage:

	The simplest form of usage is..

		$my_var = corz_GUIGetFX()

	Which will return an array of animation codes for "Slide Right" (the default
	animation). If you want to specify the animation, but don't need to (re)store
	any settings, use..

		$my_var = corz_GUIGetFX("bottom")	; or whatever

	If you want to specify an ini file for the settings, but leave everything
	else to corz_GUIGetFX(), use..

		$my_var = corz_GUIGetFX("", "C:\ini.file", "section name")

	and corz_GUIGetFX() will retrieve the last saved settings and apply them.
	If no settings were found, it creates them. At the end, it saves them.

	If you are trigerring all this from menus (as in above example), or similar,
	there's no need to do anything else, corz_GUIGetFX() will keep the ini
	file constantly updated with the latest settings.

	Another reason why you might want to interact directly with
	corz_GUIGetFX() is to override the name of the ini key/environment variable.
	Usually it is "gui_fx", but you might be animating lots of windows within a
	single application, each with individual settings.

	Then you could access the simple animation string of any window by getting
	the environment variable with its name; i.e..

		GUICtrlSetData($combo_img_tools, EnvGet('image_tools'))

	or whatever. And although you could also do this..

		corz_GUIAnimateOpen($gui_img_tools, EnvGet('image_tools'))

	you would most likely be working with the codes directly, having grabbed
	them already.

#ce
func corz_GUIGetFX($fx="", $fx_ini_path="", $fx_ini_section="corz gui fx", $fx_win = "gui_fx")
	if $fx_ini_path and $fx = "" then
		$fx = IniRead($fx_ini_path, $fx_ini_section, $fx_win, "Slide right")
	endif

	switch $fx
		case "-", "Disabled", "disable", "Disable window animation"
			local $GUIFX[3] = [2, "disable", "disable"] ; it don't like "-" here :/

		case "fade"
			local $GUIFX[3] = [2, "fade", "fade"]

		case "Slide Left", "Left", "Slide L", "l"
			local $GUIFX[3] = [2, '0x00040001', '0x00050002'] ; hex looks better darker (in my color scheme ;o)

		case "Slide Top", "Slide T", "Top", "t"
			local $GUIFX[3] = [2, '0x00040004', '0x00050008']

		case "Slide Right", "Right", "Slide R", "Slide", "r"
			local $GUIFX[3] = [2, '0x00040002', '0x00050001']

		case "Slide Bottom", "Slide B", "Bottom", "b"
			local $GUIFX[3] = [2, '0x00040008', '0x00050004']

		case "Slide Top Left", "Top Left", "top-left", "tl", "diagonal tl", "d"
			local $GUIFX[3] = [2, '0x00040005', '0x0005000a']

		case "Slide Top Right", "Top Right", "top-right", "tr", "diagonal tr"
			local $GUIFX[3] = [2, '0x00040006', '0x00050009']

		case "Slide Bottom Right", "Bottom Right", "bottom-right", "br", "diagonal br"
			local $GUIFX[3] = [2, '0x0004000a', '0x00050005']

		case "Slide Bottom Left", "Bottom Left", "bottom-left", "bl", "diagonal bl"
			local $GUIFX[3] = [2, '0x00040009', '0x00050006']

		case  "x", "Implode/Explode", "Explode/Implode", "Explode", "Implode"
			local $GUIFX[3] = [2, '0x00040010', '0x00050010']

		case "" ; deleted in the ini!
			continuecase
		case else
			$fx = "Slide Right"
			local $GUIFX[3] = [2, '0x00040002', '0x00050001']
	endswitch
	EnvSet($fx_win, $fx)
	if $fx_ini_path then IniWrite($fx_ini_path, $fx_ini_section, $fx_win, $fx)
	return $GUIFX
endfunc